home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / lisp / kcl / akcl / akcl1615.lha / README < prev    next >
Text File  |  1992-03-27  |  10KB  |  273 lines
  1. Description of AKCL system.
  2.  
  3. OVERVIEW:
  4.  
  5. The AKCL system contains original files and change files (usually V/*
  6. files).  The change files are then combined with files in the original
  7. KCL distribution.  The latter is the June 1987 version.  The utility
  8. merge, takes files from the original distribution and modifies them
  9. according to a prescription in a `change file'.  The change files
  10. reside in the directory V.  The enhancements include enhancements to
  11. the lisp compiler, loader, garbage collector and to the basic C code.
  12. If installed properly NOTHING in the original kcl directory should be
  13. overwritten.  Files which have not changed will have only a link copy
  14. in the akcl directory, and files which do change will have a changed
  15. copy in the akcl directory, and an unchanged file in the kcl
  16. directory.  To ensure that you do not accidentally alter a file in the
  17. original directory you might wish to make the files there unwritable.
  18. You do not need to do a make in the kcl directory.
  19.  
  20.  
  21. OBTAINING SOURCES:
  22. -----------------                   
  23. * There are source files on rascal.ics.utexas.edu:pub/akcl-XX.tar.Z
  24. You probably want the highest XX version number.  For example
  25. akcl-1-605.tar.Z would allow you to build the version 1-605 of AKCL.  In
  26. the following this compressed tar file is simply referred to as
  27. akcl.tar.Z.   You will also need to obtain the original kcl distribution
  28. of June 1987.  That is referred to as kcl.tar.Z and is also available
  29. on rascal.   An alternate source for these files is cli.com:akcl/akcl-XX.tar.Z
  30. In general the bandwidth to rascal is higher than to cli.com.
  31. Rascal's address is rascal.ics.utexas.edu (128.83.138.20).
  32.                    
  33. * If you cannot obtain these files via internet, a cartridge tape (sun
  34. compatible) or diskettes containing akcl, and kcl sources may be
  35. obtained for $250 US plus shipping, from J. Schelter, 1715
  36. Barnswallow, Autin TX 78746.  This would be in standard tar format.
  37. Some machines on which akcl compiles are 386 under System V (eg
  38. Microport), Sun's (sparc,sun3's), HP under hpux and 4.3, Dec mips ultrix,
  39. Sgi mips irix.
  40.  
  41. MAKING THE SYSTEM:
  42. ==================
  43. To make the whole system, if you have obtained akcl.tar.Z and
  44. kcl.tar.Z
  45.  
  46. UNCOMPRESS and UNTAR the SOURCES:
  47. --------------------------------
  48.  
  49. Change to a directory in which you wish to put the kcl and akcl
  50. subdirectories.  Make sure the two files kcl.tar.Z and akcl.tar.Z are
  51. in your current directory.    When you extract the files make sure the write
  52. file write dates are as in the distribution--make needs this.
  53.  
  54. % mkdir kcl
  55. % (cd kcl ; uncompress -c ../kcl.tar.Z | tar  xvf -)
  56. % mkdir akcl
  57. % cd akcl
  58. % uncompress -c ../akcl.tar.Z | tar  xvf -
  59.  
  60.       
  61. ADD MACHINE DEFINITIONS TO MAKEFILES:
  62. ------------------------------------
  63.  
  64. Determine the NAME of your machine by looking in the MACHINES file (eg
  65. sun3-os4).  Also remember where you untarred kcl.tar.Z (eg
  66. /public/kcl)
  67.  
  68.     % add-defs sun3-os4 /public/kcl
  69.  
  70.     (in general % add-defs NAME DIRECTORY-WHERE-KCL-IS)
  71.  
  72.     You should finally be ready to go!
  73.  
  74. RUNNING MAKE:
  75. ------------
  76.  
  77.     % make -f Smakefile 
  78.  
  79. NOTE: Smakefile is a special makefile which causes make to be run
  80. twice, the first time building a saved_kcl using some interpreted
  81. code, and the second time compiling itself.  If this does not run
  82. twice you will be using a good deal of interpreted code as well as a
  83. combination of old and new compiler, which while sufficient to compile
  84. the new compiler, would not be good for general use.  If you later
  85. change files it will be sufficient to just use the regular makefile
  86. (which has by now been slightly altered).
  87.  
  88. The make should continue without error.   There may be occasional
  89. warnings from the C compiler, but all files should compile successfully
  90. producing .o files.
  91.  
  92. The V/* change files will only be used if they are newer (normally the
  93. case) than the existing files.  If you have modified files in the akcl
  94. directory, eg. c/array.c, but wish merge to overwrite that with its
  95. merged version, you could for example % touch V/c/array.c.  Building
  96. akcl successfuly through the second pass, will mail a version info
  97. message to akcl so we know which cpu, c compiler and os levels are
  98. working properly, as well as printing out a message "Make of AKCL xxx
  99. completed", where xxx stands for the version number.
  100.  
  101. When it has finally finished you may invoke AKCL by using
  102.  
  103. TRY IT OUT:
  104. ----------
  105.  
  106. % xbin/kcl
  107. AKCL (Austin Kyoto Common Lisp)  Version(1.65) Wed Sep 21 00:52:31 CDT 1988
  108. Contains Enhancements by W. Schelter
  109. >(+ 2 3)
  110.  
  111. >5
  112.  
  113.  
  114. COPY THE COMMAND SCRIPT:
  115. -----------------------
  116.  
  117.     * You should copy xbin/kcl to /usr/local/bin or some place on users
  118.     search paths.   This is so that users may conveniently invoke the saved
  119.     image with a first arg equal to the directory where the image resides.
  120.     (some things like faslink, autoload,.. need to know the system directory).
  121.  
  122.  
  123. ELIMINATE SOME FILES?
  124. --------------------
  125.  
  126. What to keep if you have no space!  The only files which are ESSENTIAL
  127. to running of AKCL COMMON LISP once you have built the system (if you are
  128. using sfasl, as is default on a sun eg).
  129.   
  130.     unixport/saved_kcl
  131.     /usr/local/bin/akcl                (copy of xbin/akcl)
  132.  
  133.     Also if you are able to use sfasl, you may even % strip saved_kcl.
  134. Of course keeping sources, documentation, etc. is desirable.
  135.     doc/DOC
  136.     doc/DOC-keys.el
  137. And there are a few unloaded files */*.lisp which are useful to keep.
  138. For example lsp/make.lisp.
  139.  
  140.  
  141. DOCUMENTATION:
  142. ==============
  143.    If you use gnu emacs, a convenient method for viewing documentation
  144. of common lisp functions (or functions in an extended system), is
  145. provided by the doc/find-doc.el file.  This will be installed when you
  146. do make in the doc directory.  Adding the following to your .emacs
  147. file will allow you to use C-h d to find documentation.
  148.  
  149. (autoload 'find-doc "find-doc" nil t)
  150. (global-set-key "d" 'find-doc)
  151. (visit-doc-file "/public/akcl/doc/DOC")
  152.  
  153. See the file find-doc.el for more information.
  154. Otherwise you may use the describe command inside lisp.
  155. For example (describe 'print) will print out information about
  156. print.   You may also peruse the file doc/DOC.
  157.  
  158.  
  159. INSTALL:
  160. =======
  161. After the system has been built, in the main akcl directory
  162.  
  163. % make install 
  164.  
  165. will copy the command to execute kcl to the LBINDIR,
  166. and will also attempt to install the documentation interface
  167. for gnu emacs.   You will have to have write permission in the
  168. emacs directory, and LBINDIR for this, so you may need to
  169. be super user.
  170.  
  171.  
  172. TROUBLE SHOOTING (some common problems reported):
  173. ----------------   
  174.  
  175. 1) Did you extract the files with the original write dates--make
  176. depends heavily on this?
  177.  
  178. 2) Did you use -O on a compiler which puts out bad code?  Any time you
  179. change the settings or use a new c compiler this is a tricky point.
  180.  
  181. 3) A sample transcript from a correct make is included under
  182. doc/sample-make.  If yours compiles less often or does things
  183. differently, something is wrong, probably with dates or the clock on
  184. the server or something.
  185.  
  186. 4) If you can't save an image, try doing so on the file server rather
  187. than a client.
  188.  
  189. 5) Doing the make on a client with the main files on a server, has
  190. sometimes caused random breakage.  The large temp files used by the C
  191. compiler seem to sometimes get transferred incorrectly.  Solution: use
  192. the server for the compile.
  193.  
  194. 6) Did you make changes in the .defs or .h files, other than just
  195. commenting out a CC=gcc line?
  196.  
  197.  
  198. CHANGING THINGS: MAYBE EDIT TWO FILES:
  199. --------------------
  200.  
  201. Normally you should not need to edit ANY files.  There may be some
  202. parameter sizes you wish to change or if you don't have gcc where
  203. we have made that the default, then see CC below.
  204.  
  205.  
  206. EDIT the appropriate h/NAME.defs file.   These are definitions to
  207. be included in the various makefiles.
  208.  
  209. For example if the `NAME' of your machine is sun3-os4.
  210.  
  211. % emacs h/sun3-os4.defs
  212.  
  213.    * CC: set C compiler options.  For example, if you are using the GNU
  214.      C compiler:
  215.  
  216.      CC = gcc -msoft-float -DVOL=volatile -I$(AKCLDIR)/o
  217.  
  218.          Or, if you are using the conventional UNIX C compiler:
  219.  
  220.      CC = cc -DVOL= -I. -I$(AKCLDIR)/o
  221.      
  222.    * ODIR_DEBUG:
  223.      
  224.      ODIR_DEBUG= -g
  225.  
  226.      If you want files in the main c source compiled with debugging
  227.      information.   Note this is incompatible with OFLAGS= -O on
  228.      some compilers.   Size will be smaller without -g, but you
  229.      are then helpless in the face of problems.
  230.      
  231.    * INITFORM: The normal thing is to just have the one form
  232.      required for fast loading.
  233.  
  234.     INITFORM=(si::build-symbol-table)
  235.  
  236.  
  237. -----------
  238.  
  239. EDIT the file h/NAME.h  (eg h/sun3-os4.h)
  240.  
  241. (Actually you probably don't need to change it)
  242.  
  243. This file will be included by virtually every compilation of C
  244. files, except the translated C produced by kcl.
  245.  
  246. % emacs h/sun3-os4.h
  247.  
  248.       if you wish to change a parameter such as MAXPAGE 16384 established
  249.       in bsd.h (ie. number of 2000 byte pages you want as your absolute max
  250.       swap space).   MAXPAGE must be a power of 2.
  251.  
  252.       #undef MAXPAGE
  253.       #define MAXPAGE (2 * 16384)
  254.  
  255.       You may similarly redefine VSSIZE the maximum size for the value
  256.       stack (running very deep recursion interpreted may well require this).
  257.  
  258.  
  259.  
  260. DISCLAIMER:
  261. ----------
  262.  
  263. W. Schelter, the University of Texas, and other parties provide this
  264. program on an "as is" basis without warranty of any kind, either
  265. expressed or implied, including, but not limited to, the implied
  266. warranties of merchantability and fitness for a particular purpose.
  267.  
  268.  
  269. Bill Schelter 
  270. wfs@math.utexas.edu
  271.  
  272. See the file doc/contributors for a partial list of people who have
  273. made helpful contributions to ports etc.